 /*******************************************************************************
  * Copyright (c) 2004, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.core.runtime.content;

 import java.util.EventObject ;
 import org.eclipse.core.runtime.preferences.IScopeContext;

 /**
  * The content type manager provides facilities for file name and content-based
  * type lookup and content description.
  * <p>
  * This interface is not intended to be implemented by clients.
  * </p>
  *
  * @see org.eclipse.core.runtime.content.IContentTypeMatcher
  * @see org.eclipse.core.runtime.Platform#getContentTypeManager()
  * @since 3.0
  */
 public interface IContentTypeManager extends IContentTypeMatcher {

     /**
      * An event object which describes the details of a change to a
      * content type.
      * <p>
      * Types of changes include a change in the file associations or
      * a change in the encoding setting.
      * </p>
      */
     public final class ContentTypeChangeEvent extends EventObject {
         /**
          * All serializable objects should have a stable serialVersionUID
          */
         private static final long serialVersionUID = 1L;
         /*
          * The context for the setting that changed.
          *
          * @since 3.1
          */
         private IScopeContext context;

         /**
          * Constructor for a new content type change event.
          *
          * @param source the content type that changed
          */
         public ContentTypeChangeEvent(IContentType source) {
             super(source);
         }

         /**
          * Constructor for a new content type change event.
          *
          * @param source the content type that changed
          * @param context the context where a setting changed, or <code>null</code>
          * @since 3.1
          */
         public ContentTypeChangeEvent(IContentType source, IScopeContext context) {
             super(source);
             this.context = context;
         }

         /**
          * Return the content type object associated with this change event.
          *
          * @return the content type
          */
         public IContentType getContentType() {
             return (IContentType) source;
         }

         /**
          * Return the preference scope where the setting changed, or
          * <code>null</code>, if the change happened in the content type manager
          * default context.
          *
          * @return the context where the change happened, or <code>null</code>
          * @since 3.1
          */
         public IScopeContext getContext() {
             return context;
         }
     }

     /**
      * A listener to be used to receive content type change events.
      * <p>
      * Clients who reference the <code>org.eclipse.core.resources</code>
      * bundle are encouraged <em>not</em> to use this listener mechanism to
      * detect encoding changes. The Core Resources bundle will
      * detect changes to content types and notify clients appropriately
      * of potential changes to the encoding of files in the workspace
      * via the resource change mechanism.
      * </p>
      * <p>
      * Clients may implement this interface.
      * </p>
      */
     public interface IContentTypeChangeListener {

         /**
          * Notification that a content type has changed in the content type manager.
          * The given event object contains the content type which changed and must not
          * be <code>null</code>.
          *
          * @param event the content type change event
          */
         public void contentTypeChanged(ContentTypeChangeEvent event);
     }

     /**
      * A policy for refining the set of content types that
      * should be accepted during content type matching operations.
      * <p>
      * Clients may implement this interface.
      * </p>
      *
      * @see IContentTypeManager#getMatcher(IContentTypeManager.ISelectionPolicy, IScopeContext)
      * @since 3.1
      */
     public interface ISelectionPolicy {
         /**
          * Returns a subset of the given content types sorted by using a custom criterion.
          * <p>
          * The given array of content types has already been sorted using
          * the platform rules. If this object follows the same rules, further sorting
          * is not necessary.
          * </p>
          * <p>
          * The type of matching being performed (name, contents or name + contents)
          * might affect the outcome for this method. For instance, for file name-only
          * matching, the more general type could have higher priority. For content-based
          * matching, the more specific content type could be preferred instead.
          * </p>
          *
          * @param candidates an array containing content types matching some query
          * @param fileName whether it is a file name-based content type matching
          * @param content whether its a content-based content type matching
          * @return an array of content types
          */
         IContentType[] select(IContentType[] candidates, boolean fileName, boolean content);
     }

     /**
      * Content type identifier constant for platform's primary
      * text-based content type: <code>org.eclipse.core.runtime.text</code>.
      * <p>
      * All text-based content types ought to be sub types of the content type
      * identified by this string. This provides a simple way for detecting
      * whether a content type is text-based:
      * <pre>
      * IContentType text = Platform.getContentTypeManager().getContentType(IContentTypeManager.CT_TEXT);
      * IContentType someType = ...;
      * boolean isTextBased = someType.isKindOf(text);
      * </pre>
      * </p>
      */
     public final static String CT_TEXT = "org.eclipse.core.runtime.text"; //$NON-NLS-1$

     /**
      * Register the given listener for notification of content type changes.
      * Calling this method multiple times with the same listener has no effect. The
      * given listener argument must not be <code>null</code>.
      *
      * @param listener the content type change listener to register
      * @see #removeContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener)
      * @see IContentTypeManager.IContentTypeChangeListener
      */
     public void addContentTypeChangeListener(IContentTypeChangeListener listener);

     /**
      * Returns all content types known by the platform.
      * <p>
      * Returns an empty array if there are no content types available.
      * </p>
      *
      * @return all content types known by the platform.
      */
     public IContentType[] getAllContentTypes();

     /**
      * Returns the content type with the given identifier, or <code>null</code>
      * if no such content type is known by the platform.
      *
      * @param contentTypeIdentifier the identifier for the content type
      * @return the content type, or <code>null</code>
      */
     public IContentType getContentType(String contentTypeIdentifier);

     /**
      * Returns a newly created content type matcher using the given content type selection policy
      * and preference scope. If the preference scope is <code>null</code>, the default scope
      * is used.
      *
      * @param customPolicy a selection policy
      * @param context a user preference context to be used by the matcher, or <code>null</code>
      * @return a content type matcher that uses the given policy
      * @since 3.1
      */
     public IContentTypeMatcher getMatcher(ISelectionPolicy customPolicy, IScopeContext context);

     /**
      * De-register the given listener from receiving notification of content type changes.
      * Calling this method multiple times with the same listener has no
      * effect. The given listener argument must not be <code>null</code>.
      *
      * @param listener the content type change listener to remove
      * @see #addContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener)
      * @see IContentTypeManager.IContentTypeChangeListener
      */
     public void removeContentTypeChangeListener(IContentTypeChangeListener listener);
 }

